3D Graphics Programming with QuickDraw 3D 1.5.4

Picking in a View

QuickDraw 3D provides routines that you can use to manage the process of picking in a view. The view must already exist and be fully configured before you call these routines.

Q3View_StartPicking

You can use the Q3View_StartPicking function to start picking in a view.



 
TQ3Status Q3View_StartPicking (

                     TQ3ViewObject view,

                     TQ3PickObject pick);

view: A view.
pick: A pick object.

DESCRIPTION

The Q3View_StartPicking function begins the process of picking in the view specified by the view parameter, using the pick object specified by the pick parameter. After calling Q3View_StartPicking , you specify the model (for instance, by calling Q3Geometry_Submit ). When you have completely specified that model, you should call Q3View_EndPicking to complete the picking operation. The renderer attached to the specified view might need to reprocess the model data, so you should always call Q3View_StartPicking and Q3View_EndPicking in a picking loop.

SPECIAL CONSIDERATIONS

You should not call Q3View_StartPicking while picking is already occurring.

Q3View_EndPicking

You can use the Q3View_EndPicking function to end picking in a view.



 
TQ3ViewStatus Q3View_EndPicking (TQ3ViewObject view);

view: A view.

DESCRIPTION

The Q3View_EndPicking function returns, as its function result, a view status value that indicates the current state of the picking in the view specified by the view parameter. Q3View_EndPicking returns one of these four values:



 
typedef enum TQ3ViewStatus {

    kQ3ViewStatusDone,

    kQ3ViewStatusRetraverse,

    kQ3ViewStatusError,

    kQ3ViewStatusCancelled

} TQ3ViewStatus;

If Q3View_EndPicking returns kQ3ViewStatusDone , the picking has been completed and the specified view is no longer in picking mode. At that point, it is safe to exit your picking loop.

If Q3View_EndPicking returns kQ3ViewStatusRetraverse , the picking has not yet been completed. You should respecify the model by reentering your picking loop.

If Q3View_EndPicking returns kQ3ViewStatusError , the picking has failed because the renderer associated with the view encountered an error in processing the model. You should exit the picking loop.

If Q3View_EndPicking returns kQ3ViewStatusCancelled , the picking has been canceled. You should exit the picking loop.

SPECIAL CONSIDERATIONS

You should call Q3View_EndPicking only if picking is already occurring.